Getting Started

In a nutshell

Bringing up a reference gateway is three steps: get it online (serial console + WiFi), set up the OS (setup-device.sh installs Java, Python, and the Greengrass nucleus), and provision it (provision.sh runs certificate provisioning, points Greengrass at IoT Core, and deploys the components). Then you verify it with the health portal and a couple of CLI checks. Read this if: you want to stand up a gateway or explore the platform on real hardware. Before this: skim the Overview.

This page frames the journey. Every step links to the authoritative procedure in the iot-edge repository README, which is the source of truth for the exact commands and flags.

You need a physical device

This is real hardware: a CompuLab IOT-GATE-iMX8. If you don't have one, ask the DIoTS team (#digital-cpp-support). To exercise the platform purely in software instead, see Reference implementation vs. the iot-testing CLI below.

What you'll need

On your dev machine: Python 3, rsync, the AWS CLI (to look up IoT endpoints), and a bearer token for the Milwaukee Tool Certificate API (from #digital-cpp-support). Full list: the repo's Prerequisites.

Before provisioning, gather these values (details in the repo's First-time Device Setup):

Value	What it is
DEVICE_IP	The device's IP (hostname -I on the device)
MPBID	10-character uppercase hex device id, assigned at manufacturing
API_TOKEN	Short-lived M2M token for the Certificate API
IOT_ENDPOINT	Application MQTT endpoint for the target environment
IOT_DATA_ENDPOINT / IOT_CRED_ENDPOINT	AWS IoT ATS data and credential-provider endpoints
CERT_API_URL	Certificate API URL for the target environment

The three steps

1. Get online. Connect over the serial console to set a password, then join WiFi with nmcli. Once you can SSH in and know the device IP, continue. See Connecting to the Device.
2. Set up the OS. Run tools/setup-device.sh from your dev machine. It syncs the repo to the device and installs Java 11 (or 17), Python 3.11 (compiled via pyenv, so budget about 20 minutes), and the Greengrass nucleus as a systemd service.
3. Provision it. Run tools/provision.sh with the values above. It runs four phases automatically: syncs code, runs certificate provisioning (bootstrap cert, then the operational cert via MQTT fleet provisioning), points Greengrass at IoT Core, and waits for the deployment to install all components.

When provision.sh finishes, the device is fully provisioned and every component is running. Each script is safe to re-run.

Iterating on components

Once a device is provisioned, you don't reprovision to change code. A local deployment runs components straight from the checked-out source on the device and takes effect in seconds:

• All components: make deploy-all-local DEVICE_IP=<ip> MPBID=<mpbid> IOT_ENDPOINT=<endpoint>
• One component: tools/deploy-local.sh with --skip-* flags for the rest.

Local deployments take precedence over cloud ones. Hand the device back to the fleet's cloud deployment with make clear-local DEVICE_IP=<ip>. See Day-to-day Development.

Verifying a healthy device

Three quick checks confirm a working gateway:

1. Components are up. On the device: sudo /greengrass/v2/bin/greengrass-cli component list. All components should be RUNNING, except device-reporter, whose healthy state is FINISHED (it is one-shot: it writes the identity and status shadows once, then exits).
2. The certificate is operational. cat /home/compulab/edge-certs/state.json should show "phase": "operational"; check expiry with openssl x509 -in /home/compulab/edge-certs/operational/device.crt -noout -dates.
3. The dashboard is green. Open the health portal at http://<device-ip>:8080, or run make health DEVICE_IP=<ip> (on the device: sudo bash tools/health.sh). It aggregates the nucleus, components, BLE adapter, GNSS, cell signal, last upload, and cert expiry into one verdict.

To confirm scans are actually reaching the cloud, the repo's full-fleet bring-up runbook ends with a BLE-scan-to-cloud smoke check.

When something's wrong

The repo README has a thorough Troubleshooting section. The problems you're most likely to hit first:

• cert-manager stuck waiting for the bootstrap cert. The provisioner reaches the device over HTTP; a guest network with client isolation blocks it. Confirm curl http://<device-ip>:8888/csr works from your dev machine.
• Greengrass keeps disconnecting (SESSION_TAKEN_OVER). Two Greengrass instances are running with the same MQTT client id. Stop the service, pkill the stray Greengrass.jar, and start it again.
• Cert paths/endpoints come back empty (AWS_IO_TLS_CTX_ERROR). Greengrass reads config.tlog on startup and it overrides config.yaml. Delete the tlog and restart so it re-initializes cleanly.
• A component won't start. Check /greengrass/v2/logs/com.mt.edge.<component>.log (or make logs COMPONENT=<name>). Common causes: missing MPBID/IOT_ENDPOINT config, a Python dependency not installed, or cert directory permissions.

Reference implementation vs. the iot-testing CLI

The platform also ships a software test tool, the iot-testing CLI (the DIoTS device provisioning tool), which lives in its own repo, iot-testing (a sibling of iot-edge, not a folder inside it). It simulates a device: it provisions and drives device behavior from your laptop with no hardware. Use each for what it's good at:

Reach for…	When you want to…
iot-testing CLI	Exercise cloud APIs, shadows, and provisioning quickly in software, in CI, or without hardware.
Greengrass reference implementation (this section)	Surface real integration behavior on actual iMX8 hardware, running the true component runtime over cellular, that simulation can't expose.

Where the code lives

• iot-edge repo README: the authoritative setup, provisioning, deployment, and troubleshooting reference.
• tools/: setup-device.sh, provision.sh, deploy-local.sh, health.sh, factory-reset.sh.
• Health Portal: the on-device dashboard you'll use to observe and operate the gateway.